Metadata

The Feed.fm SDK delivers, by default, song level metadata to all clients: song title, artist name, release (album) name, and song duration. In addition, the Feed.fm SDK can deliver custom station-level metadata to your app. This metadata could be URLs to imagery, information about song beat rates, foreign keys, or descriptive text - anything that can be represented in a JSON object.

This write-up gives examples of how to access metadata via the native Android and iOS SDKs, and offers some suggestions for station level metadata to nicely integrate music into your application.

iOS

Song Metadata for iOS

Song metadata is available via FMAudioItem instances. The FMAudioPlayer's currentItem property holds the instance representing the active song, and the playHistory property holds past songs. The FMAudioItem's name, artist, and album properties are simple NSString * instances, will never be nil, and must be rendered by your application during playback.

FMAudioItem contains a duration property, which specifies the song duration and is sent from the Feed.fm API servers. This value might differ slightly from FMAudioPlayer's currentItemDuration property, which is calculated by the phone during audio decoding and preferable to use when the song is actively playing, so that currentPlaybackTime approaches that value exactly as a song completes playback.

Songs may have arbitrary additional data available via the FMAudioItem's metadata property, but normally this dictionary is empty. If there were data in this dictionary, it could be specific to the song regardless of what station it appears in (such as information about the history of the song or artist), or specific to the song in the particular station it is being played (such as descriptive text on why the song appears in the given station). Feed.fm curators can add arbitrary key/value pairs to this field upon request.

Station Metadata for iOS

Station level metadata is available via the name and options properties of FMStation instances, which are retrieved via the FMAudioPlayer's activeStation, stationList, localOfflineStationList, or remoteOfflineStationList properties.

Station names are defined when your Feed.fm account is set up, and should primarily be assigned with an eye towards management, curation, and reporting, and not for display to end users of the application. For simple applications, the station name often renders fine within an app and serves well as the identifier for curation and reporting. For more complex sets of stations, we recommend that, if you wish for the display name of a station to be stored with the station, you assign the display name to an entry in the station's options metadata.

warning

FMStation instances have an identifier property (not listed in the appledocs) that should not be used by client apps. This value represents a particular version of the station as new songs are added or removed, this value changes. Your application should make use of a foreign key stored in the station's options metadata rather than ever relying on this value.

The options dictionary of an FMStation can be any arbitrary JSON data that is supplied to the Feed.fm curators. This data is sent to clients and deserialized into the options NSDictionary. Common items stored in this property are:

• display name
• URL to station artwork
• foreign key
• descriptive text
• an array of station 'attributes'

The values assigned to stations are visible in the developer.feed.fm administrative interface, where they are represented as a JSON object.

Assume a station's options metadata is defined and appears in the administrative interface as:

{
  "displayname": "Chill Vibes",
  "appid": "DOWNTEMPO01",
  "visible": true,
  "genres": [ "00s", "90s", "downtempo"]
}

The station's name may be rendered by the client app as station.options[@"displayname"], and only stations where [station.options[@"visible"] isEqualTo:@TRUE] might be rendered by default within the application.

The FMStationArray array, returned via the stationList property on FMAudioPlayer, has methods to assist with selecting FMStation instances based on metadata values. For instance, to pick out all streaming stations with visible: true in their metadata, you might use:

  FMStationArray *stations = [FMAudioPlayer sharedPlayer].stationList;
  FMStationArray *visible = [stations getAllStationsWithOptionKey: @"visible" Value:@TRUE];

Or to retrieve all stations that are both visible and hold downtempo music:

  FMStationArray *visibleDowntempo = [stations getAllStationsWithOptions: @{ @"visible": @TRUE, @"genre": @"downtempo" }];

Android

Song Metadata for Android

Song metadata is available via AudioItem instances, which are usually held by a Play instance. The FeedAudioPlayer's getCurrentPlay method returns a Play instance that holds an AudioItem representing the active song, and the getPlayHistory method holds past songs. The AudioFile's getArtist, getTrack, and getRelease methods return simple objects (that are never null) that hold either a title or name property that must be rendered by your application during playback.

AudioFile contains a getDurationInSeconds method, which specifies the song duration and is sent from the Feed.fm API servers. This value might differ slightly from FeedAudioPlayer's getCurrentPlayDuration method, which is calculated by the phone during audio decoding and preferable to use when the song is actively playing, so that getCurrentPlaybackTime approaches that value exactly as a song completes playback.

Songs may have arbitrary additional data available via the AudioFile's getOptions method, but normally this map is empty. If there were data in this map, it could be specific to the song regardless of what station it appears in (such as information about the history of the song or artist), or specific to the song in the particular station it is being played (such as descriptive text on why the song appears in the given station). Feed.fm curators can add arbitrary key/value pairs to this field upon request.

Station Metadata for Android

Station level metadata is available via the getName, getOption, and containsOption methods of Station instances, which are retrieved via the FeedAudioPlayer's getActiveStation, getStationList, getLocalOfflineStationList, or getRemoteOfflineStationList methods.

Station names are defined when your Feed.fm account is set up, and should primarily be assigned with an eye towards management, curation, and reporting, and not for display to end users of the application. For simple applications, the station name often renders fine within an app and serves well as the identifier for curation and reporting. For more complex sets of stations, we recommend that, if you wish for the display name of a station to be stored with the station, you assign the display name to an entry in the station's options metadata.

warning

Station instances have a getTempId method that should not be used by client apps. This value represents a particular version of the station and, as new songs are added or removed, so does this value. Your application should make use of a foreign key stored in the station's options metadata rather than ever relying on this value.

The options map of a Station can be any arbitrary JSON data that is supplied to the Feed.fm curators. This data is sent to clients and deserialized into the options map. Common items stored in this property are:

• display name
• URL to station artwork
• foreign key
• descriptive text
• an array of station 'attributes'

The values assigned to stations are visible in the developer.feed.fm administrative interface, where they are represented as a JSON object.

Assume a station's options metadata is defined and appears in the administrative interface as:

{
  "displayname": "Chill Vibes",
  "appid": "DOWNTEMPO01",
  "visible": true,
  "genres": [ "00s", "90s", "downtempo"]
}

The station's name may be rendered by the client app as station.getOption("displayname"), and only stations where Boolean.TRUE.equals(station.getOption("visible") might be rendered by default within the application.

The StationList list, returned via the getStationList method on FeedAudioPlayer, has methods to assist with selecting Station instances based on metadata values. For instance, to pick out all streaming stations with visible: true in their metadata, you might use:

  StationList stations = FeedPlayerService.getInstance().getStationList();
  StationList visible = stations.getAllStationsWithOption("visible", Boolean.TRUE);

Or to retrieve all stations that are both visible and hold downtempo music:

  StationList visibleDowntempo = stations.getAllStationsWithOptions(new HashMap<String, Object>() {{
      put("visible", Boolena.TRUE);
      put("genre", "downtempo");
  });